Crate opentelemetry

source ·
Expand description

OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.

Compiler support: requires rustc 1.60+

Getting Started

use opentelemetry::{global, sdk::export::trace::stdout, trace::Tracer};

fn main() {
    // Create a new trace pipeline that prints to stdout
    let tracer = stdout::new_pipeline().install_simple();

    tracer.in_span("doing_work", |cx| {
        // Traced app logic here...
    });

    // Shutdown trace pipeline
    global::shutdown_tracer_provider();
}

See the examples directory for different integration patterns.

Traces

The trace module includes types for tracking the progression of a single request while it is handled by services that make up an application. A trace is a tree of Spans which are objects that represent the work being done by individual services or components involved in a request as it flows through a system.

Creating and exporting spans

use opentelemetry::{global, trace::{Span, Tracer}, KeyValue};

// get a tracer from a provider
let tracer = global::tracer("my_service");

// start a new span
let mut span = tracer.start("my_span");

// set some attributes
span.set_attribute(KeyValue::new("http.client_ip", "83.164.160.102"));

// perform some more work...

// end or drop the span to export
span.end();

See the trace module docs for more information on creating and managing spans.

Metrics

Note: the metrics specification is still in progress and subject to major changes.

The metrics module includes types for recording measurements about a service at runtime.

Creating instruments and recording measurements

use opentelemetry::{global, Context, KeyValue};

let cx = Context::current();

// get a meter from a provider
let meter = global::meter("my_service");

// create an instrument
let counter = meter.u64_counter("my_counter").init();

// record a measurement
counter.add(&cx, 1, &[KeyValue::new("http.client_ip", "83.164.160.102")]);

See the metrics module docs for more information on creating and managing instruments.

Crate Feature Flags

The following core crate feature flags are available:

  • trace: Includes the trace API and SDK (enabled by default).
  • metrics: Includes the unstable metrics API and SDK.

Support for recording and exporting telemetry asynchronously can be added via the following flags:

  • rt-tokio: Spawn telemetry tasks using tokio’s multi-thread runtime.
  • rt-tokio-current-thread: Spawn telemetry tasks on a separate runtime so that the main runtime won’t be blocked.
  • rt-async-std: Spawn telemetry tasks using async-std’s runtime.

In addition to opentelemetry, the open-telemetry/opentelemetry-rust repository contains several additional crates designed to be used with the opentelemetry ecosystem. This includes a collection of trace SpanExporter and metrics pull and push controller implementations, as well as utility and adapter crates to assist in propagating state and instrumenting applications.

In particular, the following crates are likely to be of interest:

Additionally, there are also several third-party crates which are not maintained by the opentelemetry project. These include:

If you’re the maintainer of an opentelemetry ecosystem crate not listed above, please let us know! We’d love to add your project to the list!

Supported Rust Versions

OpenTelemetry is built against the latest stable release. The minimum supported version is 1.60. The current OpenTelemetry version is not guaranteed to build on Rust versions earlier than the minimum supported version.

The current stable Rust compiler and the three most recent minor versions before it will always be supported. For example, if the current stable compiler version is 1.49, the minimum supported version will not be increased past 1.46, three minor versions prior. Increasing the minimum supported compiler version is not considered a semver breaking change as long as doing so complies with this policy.

Modules

  • attributesmetrics
    OpenTelemetry Attributes
  • baggage
    Primitives for sending name/value data across system boundaries.
  • global
    Utilities for working with global telemetry primitives
  • metricsmetrics
    OpenTelemetry Metrics API
  • propagation
    OpenTelemetry Propagator interface
  • runtime
    Provides an abstraction of several async runtimes
  • sdk
    OpenTelemetry SDK
  • tracetrace
    API for tracing applications and libraries.

Structs

Enums

Traits

  • ExportError
    Marker trait for errors returned by exporters